Relative Time
Relative time is used to specify times and time spans when fetching data.
The format for the relative time is: keyword+/-offset+/-offset… where keyword and offset are as specified in the tables below.
| Keyword | Description |
|---|---|
| SECOND | The start of the current second |
| MINUTE | The start of the current minute |
| HOUR | The start of the current hour |
| DAY | The start of the current day |
| WEEK | The start of the current week |
| MONTH | The start of the current month |
| YEAR | The start of the current year |
| NOW | The current UTC time as calculated on the server |
| Offset | Description |
|---|---|
| S | Offset from time in seconds. |
| M | Offset from time in minutes |
| H | Offset from time in hours |
| D | Offset from time in days |
| W | Offset from time in weeks |
| M | OOffset from time in months |
| Y | Offset from time in years |
White space is ignored.
All keywords and offsets are specified in uppercase.
Examples
- "NOW - 1H" The UTC time on the server when reading the history and 1 hour back.
- "NOW -1D + 1M + 45S" The UTC Time minus one day plus one minute and 45 seconds.
“DAY -1D+7H30M” could represent the start time for data request for a daily report beginning at 7:30 in the morning of the current day (DAY = the first timestamp for today, -1D would make it the first timestamp for yesterday, +7H would take it to 7 a.m. yesterday, +30M would make it 7:30 a.m. yesterday (the + on the last term is carried over from the last term).
Similarly, “MO-1D+5h” would be 5 a.m. on the last day of the previous month, “NOW-1H15M” would be an hour and fifteen minutes ago, and “YEAR+3MO” would be the first timestamp of April 1 this year.
Resolving relative timestamps is based upon what Microsoft has done with Excel, thus for various questionable time strings, we have these results:
- 10-Jan-2001 + 1 MO = 10-Feb-2001
- 29-Jan-1999 + 1 MO = 28-Feb-1999
- 31-Mar-2002 + 2 MO = 30-May-2002
- 29-Feb-2000 + 1 Y = 28-Feb-2001
Month: if the answer falls in the gap, it is backed up to the same time of day on the last day of the month.
Year: if the answer falls in the gap (February 29), it is backed up to the same time of day on February 28.
Note that the above does not hold for cases where one is adding or subtracting weeks or days, but only when adding or subtracting months or years, which may have different numbers of days in them.